using System.Text.Json.Serialization;

namespace Sage.CloudStorage.Qiniu.Models
{
    /// <summary>
    /// 完成分片上传响应类
    /// 包含分片上传成功完成后七牛云返回的最终文件信息
    /// </summary>
    /// <remarks>
    /// **成功标志**：
    /// - 收到此响应表示整个分片上传任务已成功完成
    /// - 所有分片已被合并为一个完整的文件
    /// - 文件已可通过七牛云进行访问和下载
    /// - UploadId已失效，不能再用于其他操作
    /// 
    /// **响应用途**：
    /// - 获取最终文件的访问标识
    /// - 验证文件完整性和正确性
    /// - 记录上传结果用于业务处理
    /// - 提供给客户端的上传成功确认
    /// 
    /// **后续操作**：
    /// - 可以通过Key访问和下载文件
    /// - 可以进行文件管理操作（删除、移动等）
    /// - 可以设置文件的访问权限和域名绑定
    /// - 可以触发数据处理和CDN分发
    /// </remarks>
    public class CompleteMultipartUploadResponse
    {
        /// <summary>
        /// 资源名称（文件键名）
        /// 文件在七牛云存储中的唯一标识和访问路径
        /// </summary>
        /// <remarks>
        /// **Key的作用**：
        /// - **唯一标识**：在存储空间中唯一标识此文件
        /// - **访问路径**：构成文件访问URL的路径部分
        /// - **管理标识**：用于文件管理操作的目标标识
        /// - **业务关联**：与业务系统中的文件记录关联
        /// 
        /// **URL构成**：
        /// 完整的文件访问URL格式：
        /// ```
        /// https://&lt;domain&gt;/&lt;key&gt;
        /// ```
        /// 其中domain是绑定的访问域名，key就是此字段的值
        /// 
        /// **Key格式示例**：
        /// - "documents/report_2024.pdf" - 文档类文件
        /// - "images/users/123/avatar.jpg" - 用户头像
        /// - "videos/2024/03/promotional.mp4" - 推广视频
        /// - "data/backup_20240315.zip" - 备份文件
        /// 
        /// **存储建议**：
        /// - 在业务数据库中记录Key值
        /// - 用于构建文件访问URL
        /// - 作为文件管理操作的参数
        /// - 用于CDN配置和域名绑定
        /// 
        /// **使用示例**：
        /// ```csharp
        /// // 构建文件访问URL
        /// var fileUrl = $"https://cdn.example.com/{response.Key}";
        /// 
        /// // 保存到数据库
        /// var fileRecord = new FileRecord
        /// {
        ///     Key = response.Key,
        ///     Hash = response.Hash,
        ///     UploadTime = DateTime.Now
        /// };
        /// ```
        /// 
        /// **注意事项**：
        /// - Key值区分大小写
        /// - 不能包含某些特殊字符
        /// - 长度有限制（通常最大1024字节）
        /// - 在同一存储空间中必须唯一
        /// </remarks>
        [JsonPropertyName("key")]
        public string Key { get; set; } = "";

        /// <summary>
        /// 目标资源的哈希值
        /// 可用于文件完整性验证和ETag头部设置
        /// </summary>
        /// <remarks>
        /// **Hash特性**：
        /// - 由七牛云根据完整文件内容计算生成
        /// - 全局唯一，相同内容的文件具有相同Hash
        /// - 可用作文件的指纹标识
        /// - 支持文件去重和完整性验证
        /// 
        /// **主要用途**：
        /// - **完整性验证**：确保文件在存储和传输过程中未损坏
        /// - **去重检测**：识别内容相同的重复文件
        /// - **缓存控制**：作为HTTP ETag头部使用
        /// - **版本管理**：通过Hash值判断文件是否发生变化
        /// - **安全审计**：文件内容的唯一性标识
        /// 
        /// **HTTP ETag**：
        /// Hash值可以直接用作HTTP响应的ETag头部：
        /// ```
        /// ETag: "FqvtxHpe3j-rEzkImMUWDsmvu27D"
        /// ```
        /// 支持浏览器的条件请求和缓存控制
        /// 
        /// **使用示例**：
        /// ```csharp
        /// // 文件完整性验证
        /// if (localFileHash == response.Hash)
        /// {
        ///     Console.WriteLine("文件完整性验证通过");
        /// }
        /// 
        /// // 去重检测
        /// var existingFile = database.FindByHash(response.Hash);
        /// if (existingFile != null)
        /// {
        ///     Console.WriteLine("发现重复文件");
        /// }
        /// 
        /// // 设置HTTP响应头
        /// httpResponse.Headers.ETag = new EntityTagHeaderValue($"\"{response.Hash}\"");
        /// ```
        /// 
        /// **格式特点**：
        /// - 通常为28个字符的Base64编码字符串
        /// - 使用七牛云专有的哈希算法计算
        /// - 不是标准的MD5或SHA1值
        /// - 具有很好的分布性和唯一性
        /// 
        /// **最佳实践**：
        /// - 保存Hash值用于后续的文件管理
        /// - 用于实现客户端缓存机制
        /// - 作为文件的指纹进行去重处理
        /// - 在文件同步场景中判断文件变化
        /// 
        /// **注意事项**：
        /// - Hash值由文件内容决定，不能人为修改
        /// - 文件内容发生任何变化都会导致Hash值变化
        /// - 不同存储空间中相同内容的文件Hash值相同
        /// - Hash碰撞的概率极低，可以认为是唯一的
        /// </remarks>
        [JsonPropertyName("hash")]
        public string Hash { get; set; } = "";
    }
}
